Get an answer from the Determinations Server Assess Request

Get an answer from the Determinations Server Assess request

What do you want to do?

Get an attribute as an answer

Get a relationship as an answer

Process multiple determinations within the same Assess request

Handle errors or warnings returned by the Determinations Server

Obtain a decision report from a web service

Specify outcomes for all instances of a given entity using the Outcome option

Get an attribute as an answer

You can get the answer to an attribute from the Oracle Determinations Server by using an Assess operation. Typically this attribute would be an inferred goal of a rulebase. In order to get an answer for this attribute goal you will need to provide sufficient information in the Assess operation for the answer to be inferred.

In both the generic and specific interfaces, you can ask for the value of the attribute by specifying an outcome style (outcome-style) instead of supplying a value. An outcome style tells the assess operation that you are asking for a value rather than setting one.

See also: Important Note: do not set value and specify outcome style for same attribute.

 

Example generic request

<entity id=”client”>  
    <instance id=”client-100064”>
        <attribute id=”client_is_eligible” outcome-style=”value-only” />
        ...
    </instance>
</entity>

In the example above, the attribute element with an outcome-style is inside the entity element for client-100064. This means that I am requesting the value of the attribute client_is_eligible for the client identified in my assess request by the id client-100064. The outcome-style has been specified to be value-only, meaning I am only interested in the value. Alternatively you could specify an outcome-style of decision-report or base-attributes if you wanted the answer reported with a decision report.

In the assess response, you will find all attribute elements with an outcome-style now contain the inferred value of that attribute.

As an alternative to supplying the outcome style, we can supply both the known-outcome-style and unknown-outcome-style. This allows you to control the content of the response depending on whether the inferred attribute is known or unknown. In the example below we are again requesting the value of client_is_eligible for client instance client-100064. If the value of the attribute is unknown, we want a decision report. If the value of the attribute is known, we are only interested in the value:

 

Example generic request - known and unknown outcome styles

<entity id=”client”> 
    <instance id=”client-100064”>
        <attribute id=”client_is_eligible” known-outcome-style=”value-only” unknown-outcome-style=”decision-report” />
        ...
    </instance>
</entity>

In the example response, we can see that the value returned is true (the client is eligible):

 

Example attribute in response

<entity id=”client”>
    <instance id=”client-100064”>
        <attribute id=”client_is_eligible” type=”boolean” inferred=”true”>
            <typ:boolean-val>true</typ:boolean-val>
        </attribute>
        ...
    </instance>
</entity>

Use of the specific format is very similar. The outcome-style (or both known-outcome-style and unknown-outcome-style) is specified for the element representing the attribute that we are interested in to indicate that the Determinations Server should put the value in the response:

 

Example specific request

<list-client>
      <client id=”client-100064”>
            <client_is_eligible outcome-style="value-only" />
            ...
      </client>
</list-client>

 

Example attribute in specific response

<list-client>
    <client id=”client-100064”>
        <client_is_eligible type=”boolean” inferred=”true”>
            <typ:boolean-val>true</typ:boolean-val>
        </client_is_eligible>
        ...
    </client>
</list-client>

 

Get a relationship as an answer

In the same way that you can ask for the value of an attribute as answer, you can also ask for the value of an inferred relationship. This is also done through the Assess operation, by specifying an outcome-style (or known-outcome-style and unknown-outcome-style) in the request.

 

Example generic request

<entity id=”client”> 
    <instance id=”client-100064”>
    ...
        <relationship id=”clients_eligible_children”
            outcome-style=”value-only” />
        ...
    </instance>
</entity>

 

As with attributes (see above), you can specify the outcome style to be the value (in this case all targets of the inferred relationship) or the value and a decision report.

In the assess response, you will find all relationship elements with outcome styles specified populated with all the targets of that relationship.

 

Example relationship in response

<entity id=”client”>  
    <instance id=”client-100064”>
        ...
            <relationship name=”clients_eligible_children”
                                   state=”known” inferred=”true”>
                <target instance-id=”child_100064-1”/>
                <target instance-id=”child_100064-2”/>
            </relationship>
        ...
    </entity>
</list-entity>

 

In the example response, we can see that the inferred relationship is known for the client, and that there are two eligible targets, identified by their id’s.

Use of the specific format is very similar. The outcome-style (or both known-outcome-style and unknown-outcome-style) is specified for the element representing the relationship that we are interested in to indicate that the Determinations Server should put the targets in the response:

 

Example specific request

<list-client>
      <client id=”client-100064”>
            ...
            <relationships>
                  <clients_eligible_children outcome-style=”value-only” />
            </relationships>
      </client>
</list-client>

 

Example relationship in specific response

<list-client> 
    <client id=”client-100064”>
        ...
        <relationships>
            <clients_eligible_children state=”known” inferred=”true”>
                <target instance-id=”child_100064-1”/>
                <target instance-id=”child_100064-2”/>
            </clients_eligible_children>
        </relationships>
        ...
    </client>
</list-client>


Process multiple determinations within the same Assess request

The Determinations Server is able to process multiple determinations within the same Assess request. To do this you must:

  1. Design your rulebase to concurrently determine multiple outcomes.
  2. At runtime, construct your request to send all the entities you want to reason on, and all the outcomes that you want.

Rulebase Design

You can design a rulebase in such a way that it can make multiple determinations concurrently if the determinations are attributes or, less commonly, inferred relationships belonging to a non-singleton (and not the global) entity.

Once the outcomes belong to an entity, it is possible to create multiple entities and infer the values for all entities at once.

Example

In a Human Resources department, we want to determine the number of days of leave per year an employee is eligible for. We also want to determine if that person is eligible for long service leave. Both these outcomes are based on the number of years the employee has served in the company.

This rulebase can be found in the OPA runtime directory at: examples\rulebases\compiled\EmployeeLeave.zip

Employee Attributes
Attribute Type
Date joined company Base level (input)
The employee is eligible for long service leave Inferred (outcome)
The number of days of leave per year Inferred (outcome)

 

If we decide that the employee is the global entity, and the attributes are created against this entity, then we can only infer one employee’s outcomes per session, as we can only have one global entity.

However, if we create an entity "the employee" we can then have many employees in the rulebase, and we can effectively run a batch job, getting many outcomes within in the same session and think cycle.

Assess request at runtime

If the rulebase has been designed along the principles above, we can use a single Assess request to get multiple outcomes.

This can be done with the Determinations Server, and it is also possible to do this against the Determinations Engine API directly. In both cases the principle is:

  1. Create a session with multiple entity instances
  2. Provide all the input data necessary to determine the outcomes
  3. Retrieve outcomes.
Example Assess Request and Response

In the following example request, we are sending an Assess request with three employee entities. For each of these entities we are asking for the outcomes for the number of days of annual leave each employee is entitled to, and also whether the employee is eligible for long service leave. Because these outcomes are on the employee entity we can ask for outcomes for multiple employee entities, effectively doing a batch request.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:typ="http://oracle.com/determinations/server/10.4/rulebase/assess/types">
   <soapenv:Header/>
   <soapenv:Body>
      <typ:assess-request>
         <typ:config>
            <typ:outcome>
               <typ:entity id="employee">
                  <typ:attribute-outcome id="employee_days_leave_per_year" outcome-style="value-only"/>
                  <typ:attribute-outcome id="employee_long_service_leave" outcome-style="value-only"/>
               </typ:entity>
            </typ:outcome>
         </typ:config>
         <typ:global-instance>
            <typ:entity id="employee">
               <typ:instance id="employee1">
                  <typ:attribute id="employee_date_joined_company">
                     <typ:date-val>1986-02-16</typ:date-val>
                  </typ:attribute>
               </typ:instance>
               <typ:instance id="employee2">
                  <typ:attribute id="employee_date_joined_company">
                     <typ:date-val>2001-01-01</typ:date-val>
                  </typ:attribute>
               </typ:instance>
               <typ:instance id="employee3">
                  <typ:attribute id="employee_date_joined_company">
                     <typ:date-val>1992-12-16</typ:date-val>
                  </typ:attribute>
               </typ:instance>
            </typ:entity>
         </typ:global-instance>
      </typ:assess-request>
   </soapenv:Body>
</soapenv:Envelope>

In the following response, we can see that for each employee we have an answer for the two outcomes we requested. We can parse the returned XML and get the outcomes for each employee.

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:i18n="http://www.w3.org/2005/09/ws-i18n" xmlns:typ="http://oracle.com/determinations/server/10.4/rulebase/assess/types">
   <SOAP-ENV:Header>
      <i18n:international>
         <i18n:locale>en_US</i18n:locale>
         <i18n:tz>GMT+0800</i18n:tz>
      </i18n:international>
   </SOAP-ENV:Header>
   <SOAP-ENV:Body>
      <typ:assess-response>
         <typ:global-instance>
            <typ:entity id="employee" inferred="false">
               <typ:instance id="employee1">
                  <typ:attribute id="employee_days_leave_per_year" type="number" inferred="true">
                     <typ:number-val>27.5</typ:number-val>
                  </typ:attribute>
                  <typ:attribute id="employee_long_service_leave" type="boolean" inferred="true">
                     <typ:boolean-val>true</typ:boolean-val>
                  </typ:attribute>
                  <typ:attribute id="employee_date_joined_company" type="date">
                     <typ:date-val>1986-02-16</typ:date-val>
                  </typ:attribute>
               </typ:instance>
               <typ:instance id="employee2">
                  <typ:attribute id="employee_days_leave_per_year" type="number" inferred="true">
                     <typ:number-val>20.5</typ:number-val>
                  </typ:attribute>
                  <typ:attribute id="employee_long_service_leave" type="boolean" inferred="true">
                     <typ:boolean-val>true</typ:boolean-val>
                  </typ:attribute>
                  <typ:attribute id="employee_date_joined_company" type="date">
                     <typ:date-val>2001-01-01</typ:date-val>
                  </typ:attribute>
               </typ:instance>
               <typ:instance id="employee3">
                  <typ:attribute id="employee_days_leave_per_year" type="number" inferred="true">
                     <typ:number-val>24.5</typ:number-val>
                  </typ:attribute>
                  <typ:attribute id="employee_long_service_leave" type="boolean" inferred="true">
                     <typ:boolean-val>true</typ:boolean-val>
                  </typ:attribute>
                  <typ:attribute id="employee_date_joined_company" type="date">
                     <typ:date-val>1992-12-16</typ:date-val>
                  </typ:attribute>
               </typ:instance>
            </typ:entity>
         </typ:global-instance>
      </typ:assess-response>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

See also:

Assess Request and Response Elements

Example: Assess Request xml

Example: Assess Response xml

Handle errors or warnings returned by the Determinations Server

The Determinations Server will return Error and Warning events that may happen during an assess operation.

For Warninngs, you must specify in the assess-request that you want any warning returned. You can do this by setting the optional “show-events” attribute of the assess-request “config” element. This is the same for both the Specific and Generic service.

 

Example

<assess-request>
      <config>
            <show-events>true</showevents>
      </config>
      <!-- generic or specific session data follows -->
      …
</assess-request>

 

When show events has been set to true, any warning events will display at the top of the assess-response.

 

Example

<event entity-id="child" instance-id=”child_1” name="warning">  
    <message>"the child's age might be incorrect"</message>
    <parameters>
        <value>"the child's age might be incorrect"</value>
    </parameters>
    <decision-report report-style="base-attributes">
        <attribute-node id="dn:1" entity-id="global" instance-id="global" hypothetical-instance="false" attribute-id="child_age"
          type="text" text=" The child's age is 200.0." inferred="false">
            <number-val>200.0</number-val>
        </attribute-node>
    </decision-report>
</event>

 

A warning event is always returned with the entity and a decision report attached.

For error events, no configuration is needed. Error events will always return a SOAP Fault if and error is raised in the inferencing.

 

Example

<SOAP-ENV:Fault>
      <faultcode>SOAP-ENV:Client</faultcode>
      <faultstring>The Rulebase generated an error event</faultstring>
      <detail>
            <typ:error-response>
                  <typ:code>assess.request.event.error</typ:code>
                  <typ:message>The Rulebase generated an error event</typ:message>
            </typ:error-response>
      </detail>
</SOAP-ENV:Fault>

Obtain a decision report from a web service

Get a decision report showing the rules used to reach a decision

When you request an outcome from the Determinations Server, you have control over what information is returned:

 

You can also ask for different information to be returned depending on the whether the outcome in known or unknown; for example, if the outcome is known, you may just want the value, but, if the outcome is unknown, you may want a full decision report.

When you request an attribute or relationship outcome you can specify what information you want displayed by setting the following XML attributes on the attribute or relationship element in the Assess request.

outcome-style:

this attribute controls the style of the outcome generally (regardless of when it is known or unknown.

known-outcome-style:

this attribute controls the style of the outcome when the outcome is known.

unknown-outcome-style:

this attribute controls the style of the outcome when the outcome is known.

 

For every outcome, you must specify either the outcome-style, or both the known-outcome-style and unknown-outcome-style.

The valid values for outcome styles are value-only, decision-report and base-attributes.

value-only

will return only the value for the outcome.

decision-report

will return a full decision report including all inferred attributes and relationships relationships that are relevant to the outcome.

base-attributes

will return a decision report, but only base level (non-inferred) attributes and relationships that are relevant to the outcome.

 

Request - Attribute outcome with decision report

<assess-request> 

    <global-instance>

        ...

        <attribute id="eligible_teenage_child_allowance" known-outcome-style=

            "value-only" unknown-outcome-style="decision-report"/>

        ...

    </global-instance>

</assess-request>

Request - Relationship outcome with decision report

<assess-request>

    <global-instance>

        ...

        <relationship id="eligible_children" known-outcome-style=

            "value-only" unknown-outcome-style="decision-report"/>

        ...

    </global-instance>

</assess-request>

Response with decision report

In the example response below, you can see that the requested attribute eligible_teenage_child_allowance is unknown.

The decision report explains that the contributing entities, attributes and relationships are:

 

By examining the decision report you can see that the reason that the attribute is unknown is because the child’s age in unknown for child_3.

 

Example

<typ:assess-response>  

    <typ:global-instance>

        ...

        <typ:attribute id="eligible_teenage_allowance" type="boolean" inferred="false">

            <typ:unknown-val/>

            <typ:decision-report report-style="decision-report">

                <typ:attribute-node id="dn:0" entity-id="global" instance-id="global" hypothetical-instance="false" attribute-id="eligible_

                  teenage_allowance" type="boolean" text="Is the claimant eligible for the teenage child allowance?" inferred="false">

                    <typ:unknown-val/>

                    <typ:relationship-node id="dn:1" source-entity-id="global" source-instance-id="global" hypothetical-instance="false"

                      target-entity-id="child" relationship-id="claimantschildren" state="known" inferred="false">

                        <typ:target instance-id="child1"/>

                        <typ:target instance-id="child2"/>

                        <typ:target instance-id="child3"/>

                    </typ:relationship-node>

                    <typ:attribute-node id="dn:2" entity-id="child" instance-id="child1" hypothetical-instance="false" attribute-id="child_

                      teenager" type="boolean" text="The child is not a teenager." inferred="true">

                        <typ:boolean-val>false</typ:boolean-val>

                        <typ:attribute-node id="dn:3" entity-id="child" instance-id="child1" hypothetical-instance="false" attribute-id="child_age"

                           type="number" text="The child's age is 8." inferred="false">

                            <typ:number-val>8.0</typ:number-val>

                        </typ:attribute-node>

                    </typ:attribute-node>

                    <typ:attribute-node id="dn:4" entity-id="child" instance-id="child2" hypothetical-instance="false" attribute-id="child_

                      teenager" type="boolean" text="The child is not a teenager." inferred="true">

                        <typ:boolean-val>false</typ:boolean-val>

                        <typ:attribute-node id="dn:5" entity-id="child" instance-id="child2" hypothetical-instance="false" attribute-id="child_age"

                          type="number" text="The child's age is 11." inferred="false">

                            <typ:number-val>11.0</typ:number-val>

                        </typ:attribute-node>

                    </typ:attribute-node>

                    <typ:attribute-node id="dn:6" entity-id="child" instance-id="child3" hypothetical-instance="false" attribute-id="child_

                      teenager" type="boolean" text="Is the child a teenager?" inferred="false">

                        <typ:unknown-val/>

                        <typ:attribute-node id="dn:7" entity-id="child" instance-id="child3" hypothetical-instance="false" attribute-id="child_age"

                         type="number" text="The child's age is unknown." inferred="false">

                            <typ:unknown-val/>

                        </typ:attribute-node>

                    </typ:attribute-node>

                </typ:attribute-node>

            </typ:decision-report>

        </typ:attribute>

        ...

    </typ:global-instance>

</typ:assess-response>


Control the information included in a decision report

There are several ways in which you can control information included in a decision report. The first way is to set the silent and invisible options on the attribute (see authoring > attributes > silent and invisible).

In addition to controlling the attributes that appear through their silent/invisible properties when authoring the rulebase, for the Determinations Server you can also set a decision report to base-attributes. This is specified when you request an attribute or relationship outcome in an Assess operation. When this value is set for the decision report style no inferred attributes will be returned, only base level attributes.

See Assess Operation Request and Response Elements for more information on outcome-styles.

Example - generic

<attribute id="eligible_teenage_child_allowance" outcome-style="base-attributes"/> 

<relationship id="eligible_children" outcome-style="base-attributes"/>

Example - specific

<eligible_teenage_child_allowance outcome-style="base-attributes"/> 
<eligible_children outcome-style="base-attributes"/>

Specify outcomes for all instances of a given entity using the Outcome option

In the example that follows, we specify the attribute outcomes "B.Benefit_Amount" and "monthly_benefit_timeline" as well as the relationship outcome "the_payments" for every single instance of the entity "the_benefit". The outcome-style is used to specify the level of detail that will be provided in the decision report; a full decision report will returned.

Example: 
<typ:assess-request>
         <typ:config>
            <typ:outcome>
               <typ:entity id="the_benefit">
                  <typ:attribute-outcome id="B.Benefit_Amount" outcome-style="decision-report"/>
              <typ:attribute-outcome id="monthly_benefit_timeline" outcome-style="decision-report"/>
                  <typ:relationship-outcome id="the_payments" outcome-style="decision-report"/>
               </typ:entity>
               <typ:entity id="the_payment">
                  <typ:attribute-outcome id="P.Payment_Amt" outcome-style="decision-report"/>
               </typ:entity>
            </typ:outcome>
         </typ:config>

The following describes each of the elements used in the above example (more information can be found in Assess Operation Request and Response Elements in the Technical Reference section):

outcome

Specifies the assess outcomes.

entity id

Specifies the public name of the entity.

attribute-outcome id

Corresponds to the public name of the attribute.

relationship-outcome id

Corresponds to the public name of the relationship.

outcome-style

This is the default outcome-style to use whether known or unknown. The outcome style attribute can be "value-only" (no decision report, just the value), "base-attributes" (a decision reports showing the relevant attributes, but only the base level ones), and "decision-report" a full decision report.